---
title: "Theming: Colours & Dark Mode"
---

Control the overall colour scheme and colour of individual elements

## Overview

* Change individual [colour parameters](#color-parameters)
* Switch between [light and dark colour schemes](#colour-schemes) using parts
* Integrate with a website that has a dark mode toggle using [theme modes](#theme-modes)
* Make unrestricted [customisations using CSS](./theming-css/#custom-css-rules)

## Colour Parameters

The grid has a few key colour parameters that most applications will set custom values for, and many more specific colour parameters that can be used for fine tuning. Appropriate default values for many parameters are automatically generated based on the key parameters:

* `backgroundColor` - typically your application page background (must be opaque)
* `foregroundColor` - typically your application text colour
* `accentColor` - the colour used for highlights and selection; your organisation's primary brand colour often works well.

Key colours are mixed together to make default values for all other colours that you can override to fine tune the colour scheme. For example, the default border colour is generated by mixing the background and foreground colours at a ratio of 85% background to 15% foreground. This can be overridden by setting the `borderColor` parameter.

Some commonly overridden colour parameters are:

* `borderColor` - the colour of all borders, see also [Customising Borders](./theming-borders/)
* `dataBackgroundColor` - the background colour of the grid data area
* `headerBackgroundColor` - the background colour of the header rows
* `chromeBackgroundColor` - the background colour of the grid's chrome (header, tool panel, etc)
* `textColor`, `headerTextColor`, `cellTextColor` - override text colours for UI, for headers and cells respectively

Many more parameters are available, search the "All Parameters" section of the [theme builder](/theme-builder/) for a full list.

For example:

```js
const myTheme = themeQuartz.withParams({
    backgroundColor: 'rgb(249, 245, 227)',
    foregroundColor: 'rgb(126, 46, 132)',
    headerTextColor: 'rgb(204, 245, 172)',
    headerBackgroundColor: 'rgb(209, 64, 129)',
    oddRowBackgroundColor: 'rgb(0, 0, 0, 0.03)',
    headerColumnResizeHandleColor: 'rgb(126, 46, 132)',
});
```

{% gridExampleRunner title="Colour Customisation" name="color-customisation" exampleHeight=400 suppressDarkMode=true /%}

## Extended Syntax for Colour Values

All theme parameters with the suffix `Color` are colour values, and can accept the following values:

| Syntax | Description |
|-|-|
| `string` | A [CSS colour value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value), such as `'red'`, `'rgb(255, 0, 0)'`, or variable expression `'var(--myColorVar)'`. |
| `{ ref: 'accentColor' }` | Use the same value as the `accentColor` parameter |
| `{ ref: 'accentColor', mix: 0.25 }` | A mix of 25%, `accentColor` 75% transparent |
| `{ ref: 'accentColor', mix: 0.25, onto: 'backgroundColor' }` | A mix of 25%, `accentColor` 75% `backgroundColor` |

## Colour Schemes

The grid defines a number of dark and light colour schemes that you can apply.

 * `colorSchemeVariable` - the default colour scheme for all our [built-in themes](./themes/#built-in-themes). By default it appears light, but can be adjusted using [theme modes](#theme-modes) (see below).
 * `colorSchemeLight` - a neutral light colour scheme
 * `colorSchemeLightWarm`, `colorSchemeLightCold` - light colour schemes with subtle warm and cold tints
 * `colorSchemeDark` - a neutral dark colour scheme
 * `colorSchemeDarkWarm` - dark colour scheme with subtle warm tint
 * `colorSchemeDarkBlue` - blue tinted colour scheme as used in dark mode on this website

Colour schemes are applied to themes using `withPart()`:

```js
import { colorSchemeDark } from 'ag-grid-community';

const myTheme = themeQuartz.withPart(colorSchemeDark);
```

{% gridExampleRunner title="Colour Scheme" name="color-scheme" /%}

A colour scheme is simply a theme part with values defined for the key colour parameters, so if none of the built-in schemes suit, choose the one that is closest to your needs and override parameters as required:

```js
const myTheme = themeQuartz
    .withPart(colorSchemeDarkBlue)
    .withParams({
        // We prefer red to blue. Because the built in colour schemes
        // derive all colours from foreground, background and
        // accent colours, changing these two values is sufficient.
        backgroundColor: 'darkred',
        accentColor: 'red',
    });
```

## Theme Modes

The standard way of changing a grid's appearance after initialisation is to update the value of the `theme` grid option. You might implement a dark mode toggle by preparing light and dark versions of a theme and switching between them in response to a button press.

Often however, a grid application is embedded within a website, and the website and grid application have different codebases. It may not be easy to update the theme grid option in response to the website's dark mode changing.

For this use case we provide theme modes. When a theme uses the `colorSchemeVariable` colour scheme, which is the default for our [built-in themes](./themes/#built-in-themes), the colour scheme can be controlled by setting the `data-ag-theme-mode="mode"` attribute on any parent element of the grid, commonly the `html` or `body` elements, where `mode` is any of:

 * `light`
 * `dark`
 * `dark-blue`

It is also possible to define your own colour modes, by passing the mode name to the second parameter of `withParams`. This example defines custom colour schemes for light and dark mode and switches between them by setting the `data-ag-theme-mode` attribute on the `body` element:

```js

const myTheme = themeQuartz
    .withParams(
        {
            backgroundColor: '#FFE8E0',
            foregroundColor: '#361008CC',
            browserColorScheme: 'light',
        },
        'light-red'
    )
    .withParams(
        {
            backgroundColor: '#201008',
            foregroundColor: '#FFFFFFCC',
            browserColorScheme: 'dark',
        },
        'dark-red'
    );
```

{% gridExampleRunner title="Theme Mode" name="theme-mode" /%}